home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Tools & Apps / Testing & Debugging / Virtual User Libraries & Tools / VU Aid ReadMe < prev   
Encoding:
Text File  |  1992-05-08  |  6.9 KB  |  180 lines  |  [ttro/ttxt]
  1. ______________________________________________________________________
  2. VU Aid ReadMe (1.0.8)
  3.  
  4. ______________________________________________________________________
  5. WHAT'S NEW TO THIS RELEASE
  6.  
  7.     New WindowCompare and ScreenCompare modules!  WindowCompare
  8.     allows checksumming of the frontmost window as well as a portion of the window.
  9.     Similarly for ScreenCompare allows checksumming of the main screen and any
  10.     smaller portion defined by the user.  These updated modules must be used in
  11.     invisible mode (see below) in order to work correctly.
  12.  
  13. ______________________________________________________________________
  14. WHAT IT IS
  15.  
  16.     VUAid is a collection of code modules which return information about the
  17.     CPU. These code modules act as a supplement to Virtual User, and are called
  18.     within VU scripts using the "VUAidLib.vu" library tasks.
  19.  
  20. ______________________________________________________________________
  21. INSTALLATION
  22.  
  23.     To use VUAid, launch the "VUAid Installer" application on your target CPU.  Then
  24.   select Install VUAid menu item.  If the installation is successful, a dialog appears
  25.   with a 'successful installation' message. 
  26.  
  27. ______________________________________________________________________
  28. OPERATING VUAID
  29.  
  30.     VUAid is installed as FKEY zero. To operate it, you (or your script) will
  31.     press shift-command-zero. Then you will type a command, followed by a list
  32.     of parameters. Parameters are separated by spaces. To include spaces within
  33.     a parameter, surround it with double quotes ("). To include a double quote
  34.     within a quoted parameter, double the double quote.
  35.     
  36.     Example: "here->""<-it is" will be parsed as the string “here->"<-it is”.
  37.  
  38. ______________________________________________________________________
  39. INVISIBLE MODE
  40.  
  41.     At times, you may wish to operate VUAid invisibly. Examples are for VCMDs
  42.     which checksum the front window, or do other screen operations.
  43.     
  44.     To enter invisible mode, press the caps lock key before you invoke VUAid.
  45.     
  46.     VUAid will work just as before in invisible mode, but will not alter
  47.     the screen contents. The special keys return, enter, command-Q, and
  48.     command-period all behave as before. The delete key behaves differently in
  49.     invisible mode: It deletes everything that has been entered so far, rather
  50.     than only the last character.
  51.     
  52.     Since VUAid is usually run from a VU script, the lack of visual feedback
  53.     should be ok.
  54.  
  55. ______________________________________________________________________
  56. INSTALLED MODULES
  57.  
  58.     To see which modules are installed, type "Help" in the VUAid window and
  59.     press the Execute button.
  60.  
  61. ______________________________________________________________________
  62. FORMAT OF MODULES
  63.  
  64.     Any code module which returns a value may be bundled into VUAid. To submit
  65.     a code module for inclusion, the code module must satisfy the following:
  66.  
  67.     1. It must be written in MPW C, and submitted as a folder with all source
  68.     code and include files. The folder should include a make file which contains
  69.     all build commands to build the code resource.
  70.  
  71.     2. It must reside within a single code segment.
  72.     
  73.     3. It may not use any A5 world storage. This includes static local variables
  74.     as well as global variables
  75.  
  76.     4. It should not allocate any permanent space on the heap, although it may
  77.     temporarily allocate memory, as long as disposes of all storage before
  78.     returning. (See below for exceptions.)
  79.     
  80.     5. It may not alter the environment in any way, except in those ways which
  81.     are specific to the function of the command. So a module whose function is
  82.     to set a byte of memory may alter a single memory, but should not change the
  83.     current GrafPort.
  84.     
  85.     6. The entry point must be a single function which returns a value. This
  86.     value may be a numeric value (char, short, or long), or a string (char * or
  87.     StringPtr). If necessary, a structure may be returned, although this is
  88.     undesirable.
  89.  
  90.     7. The code must not call any manager initialization functions, such as
  91.     InitDialogs().
  92.  
  93. MODULE DECLARATION
  94.  
  95.     Modules are called using a command line syntax. For instance, one command
  96.     may set a word of memory. It will be invoked with the command line:
  97.     
  98.         sw 0 1024
  99.     
  100.     VUAid will parse this line before passing dispatching to the module. It
  101.     will set up the following parameter tables:
  102.     
  103.         argc = 2
  104.         
  105.         argv[0] = "\p0 1024"
  106.         argv[1] = "\p0"
  107.         argv[2] = "\p1024"
  108.         
  109.         argn[1] = 0
  110.         argn[2] = 1024
  111.     
  112.     The parameters are:
  113.     
  114.         {argc} is the number of parameters, excluding the name of the module.
  115.     
  116.         {argv[]} is a table of StringPtr's. {argv[i]} contains the text of the
  117.         i-th parameter, where i=1 is the first parameter. {argv[0]} is a special
  118.         entry which contains a string will all the parameters, unparsed. This is
  119.         useful if you wish to use unparsed parameters or to parse the parameters
  120.         yourself. {argv[i]} where i > {argc} has an undefined value.
  121.     
  122.         {argn[]} is a table of long numbers (32 bits). These are the values of
  123.         the corresponding {argv[]} entries, as given by StringToNum(). Note that
  124.         {argn[0]} has an undefined value. {argn[i]} where i > {argc} also has an
  125.         undefined value.
  126.  
  127.     Modules are stand-alone code resources. The entry point is the start of
  128.     the code resource. The resource type is 'vcmd'. The main entry should be
  129.     declared:
  130.     
  131.         OSErr main(StringPtr result, short argc, StringPtr *argv, long *argn);
  132.     
  133.     Parameters here are:
  134.     
  135.         {result} is the string result to be returned, if any. It points to a
  136.         Str255 allocated by the caller (you do not need to allocate space for
  137.         it). If a numeric value is to be returned, it must be converted to a
  138.         string (e.g., using NumToString()). If no result is to be returned,
  139.         {result} should remain untouched. DO NOT RETURN ERROR RESULTS IN
  140.         {result}. Indicate errors using the return value, as noted below.
  141.  
  142.         {argc}, {argv}, and {argn} are described above. Note that the latter
  143.         two parameters are pointers to tables of StringPtrs and longs,
  144.         respectively.
  145.     
  146.         The return value should be an OSErr. It should be noErr (zero) if the
  147.         module executes successfully, the appropriate OSErr if one occurs, or
  148.         the special value 1 if there is an error in the parameters. For example,
  149.         the 'sw' module expects two parameters. The first must be an even
  150.         value. The second must be a word. The module should check all its
  151.         parameters first, and return an error of 1 if any are incorrect.
  152.     
  153.     Example: The following is the code for the 'sw' module. Note that it also
  154.     checks to see that the memory was set as expected. If not, it returns an
  155.     error code of -1.
  156.     
  157.         OSErr main(StringPtr result, short argc, StringPtr *argv, long *argn)
  158.         
  159.         /*
  160.             Set the contents of a word. We require exactly one parameter. If it
  161.             is an odd address, or if the data is too large for a word, we return
  162.             a parameter error. If the memory is not set, we return a -1 error.
  163.         */
  164.         
  165.         {
  166.             if (argc != 2 || argn[1] & 1 || argn[2] & 0xFFFF0000) return 1;
  167.             else {
  168.                 short *p = (short*)(argn[1]);
  169.                 *p = argn[2];
  170.                 return (*p == argn[2]) ? noErr: -1;
  171.             }
  172.         }
  173.  
  174. EXAMPLES
  175.  
  176.     See the Example Module folder for an example of a module with source code
  177.     and make file.
  178.  
  179. EOF
  180.